home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / gcc / gcc222_2.lha / docs / dlink.doc < prev    next >
Text File  |  1992-01-14  |  10KB  |  251 lines
  1.  
  2. dlink/dlink                             dlink/dlink
  3.  
  4.                   DLINK.DOC
  5.  
  6.     DLINK <options> <files> <libraries>
  7.  
  8.     Options may occur anywhere on the command lines.  Any file ending in
  9.     .o[bj] is assumed to be an object file.  Any file ending in .l[ib] is
  10.     assumed to be a library.  Any file name beginning with @ specifies a
  11.     text file containing a further list of files.
  12.  
  13.     File ordering is maintained.  Section ordering is maintained.  All
  14.     sections of the same name are coagulated together with ordering
  15.     maintained.  EXCEPTION: inter-section ordering is not maintained
  16.     within a library since library modules are random included.  However,
  17.     ordering is maintained *between* libraries.
  18.  
  19.     All object files specified are included in the final executable.  All
  20.     libraries specified are searched at the point they are specified (that is,
  21.     specifying an object file that references a symbol defined in a library
  22.     specified BEFORE the object file will cause an undefined symbol error).
  23.     Normally an object file is specified after a library to terminate an
  24.     autoinit or autoexit section.
  25.  
  26.     You do not have to order object files within a library, DLink will
  27.     automatically make as many passes as required to handle all internal
  28.     library references.  However, ordering object files will make DLink go
  29.     faster.
  30.  
  31.     Symbols defined in object files overide symbols defined in libraries.
  32.     Symbols defined in libraries specified before later libraries overide
  33.     symbols defined in later libraries.  Symbols defined in a library and
  34.     also defined in a later specified object module causes an error.
  35.  
  36.                 CREATING A LIBRARY
  37.  
  38.     DLink libraries are standard Amiga libraries... simply join one or more
  39.     object modules together and rename the result with a .lib extension.
  40.  
  41.              LINKER SYMBOLS AND A4 RELATIVE ADDRESSING
  42.  
  43.     DLink generates the following special symbols to aid in program
  44.     startup:
  45.  
  46.     __ABSOLUTE_BAS  base of data in volatile space.  This symbol is NOT
  47.             defined for normal residentable programs since the
  48.             base address is not known (must be allocated run-time)
  49.  
  50.     __DATA_BAS        base of data in non-volatile space.  This symbol points
  51.             to a read-only copy of the initialized data for a
  52.             program.  For Non-residentable programs this is the
  53.             same as __ABSOLUTE_BAS.
  54.  
  55.             For residentable programs this points to a read-only
  56.             copy of the initialized data that the program can
  57.             duplicate on startup.
  58.  
  59.             For programs linked with an absolute base address for
  60.             data this points to the end of the CODE section.  The
  61.             ROMABLE program always generates a ROM copy of the
  62.             initialized data just after the CODE section (which
  63.             startup code must copy into RAM)
  64.  
  65.     __DATA_LEN        Length of data space is LONGWORDS.    I.E. __DATA_LEN * 4
  66.             yields the number of bytes of initialized data.  This
  67.             is used by startup code to copy read-only initialized
  68.             data to volatile space (residentable and data-absolute
  69.             programs)
  70.  
  71.     __BSS_LEN        Length of bss space in LONGWORDS.  I.E. __BSS_LEN * 4
  72.             yields the number of bytes of uninitialized (BSS) data.
  73.             This is used in combination with __DATA_LEN to allocate
  74.             the DATA+BSS space for residentable programs, and clear
  75.             the BSS space for non-residentable and absolute-
  76.             data-base programs.
  77.  
  78.             The BSS space occurs after the DATA space unless the
  79.             -frag option is used.
  80.  
  81.     __RESIDENT        This symbol is set to 0 if the -r option was used and
  82.             1 if the -r option was not used.  If set to 1 (-r
  83.             option), then NO BSS SPACE IS PREALLOCATED WHEN THE
  84.             PROGRAM IS RUN.  The startup code must allocate DATA+BSS
  85.             space, copy read-only initialized data over to this
  86.             space, and clear out the BSS portion before it the
  87.             program can run.
  88.  
  89.             Programs linked with the -mw or -ma options obviously
  90.             do not 'allocate' their data space since it is
  91.             predefined.  Most Amiga programmers will never use
  92.             the -mw or -ma options, by the way.
  93.  
  94.  
  95.                 SMALL DATA MODEL
  96.  
  97.     The small data model uses A4 relative addressing.  The linker sets up
  98.     all relative offsets such that A4 must be initialized by startup code
  99.     the BaseOfInitializedData + 32766 for A4-relative references to access
  100.     the appropriate address.
  101.  
  102.                     RESIDENT
  103.  
  104.     If the -r options is given then NO BSS SPACE is allocated after the
  105.     data space... the startup code MUST allocate a data+bss space as shown
  106.     above.  DLink will give error messages for any absolute data references
  107.     that occur (except the __DATA_BAS symbol which must be used to copy the
  108.     static data to the newly allocated data+bss memory on program startup).
  109.  
  110.     DLink will give an error message if any data-data reloco32s exist when
  111.     you specify the -r option as such relocations would be incorrect when
  112.     copied to the newly allocated data+bss space.  DC1 understands this and
  113.     will produce autoinit code to handle any such static data relocations
  114.     that occur in your C code when the -r option is given to compile a C
  115.     program.
  116.  
  117.     However, DLink does allow data-data relocations to occur if an absolute
  118.     data base is specified along with the -r option.  This is used only
  119.     when making ROMABLE code.
  120.  
  121.                    PC-RELATIVE
  122.  
  123.     Because the linker will insert a jump table for PC-RELATIVE references
  124.     to different hunks (after coagulation) or where the range is larger
  125.     than +/-32K, data should not be placed into a code segment and be
  126.     referenced via an external label(pc) unless you are positive the
  127.     reference is within +/-32K.  This can only happen when referencing
  128.     between like-named code hunks.  NOTE that the jump table is tagged
  129.     onto the end of the section the jump(s) occur in and thus you do
  130.     not want to have any autoinit/autoexit code that might possibly
  131.     generate a jump table (since the whole idea with autoinit is that
  132.     the code falls through to other autoinit code until the terminating
  133.     section in x.o's RTS).
  134.  
  135.     Currently dlink cannot handle inter-module PC-RELATIVE references
  136.     beyond +/-32K (i.e. when one object file has more than 32K of code).
  137.     An error will occur.
  138.  
  139.     Note that if -frag is used you cannot make PC-RELATIVE calls
  140.     between sections of differing names ever, or make a program resident.
  141.     The -frag option is almost never used on untested.
  142.  
  143.                 OVERLAYS (NOT SUPPORTED)
  144.  
  145.     Overlays are not supported as yet.
  146.  
  147.                      OPTIONS
  148.  
  149.     Options:
  150.  
  151.     -o execname     name of executable
  152.  
  153.     -s            Include symbolic information.  NOTE, if -r is used
  154.             symbolic info for the data sections will point to
  155.             the statically init'd stuff, NOT The actual data
  156.             space (in BSS) referenced by the code.  This is a bug.
  157.  
  158.     -frag        Fragment output file (default is to coagulate all
  159.             hunks of the same type regardless of name).  If
  160.             frag is specified then only hunks of the same type
  161.             AND name are coagulated.
  162.  
  163.             see fragmentation note at bottom
  164.  
  165.     -r[es]        Resident link.
  166.  
  167.     -mw addr        specify absolute data base
  168.     -ma addr        specify absolute data base
  169.  
  170.             Both options do exactly the same thing and are in
  171.             duplicate to conform to DCC's options.
  172.  
  173.             -mw/-ma specify the base of data as a decimal,
  174.             0octal, or 0xHEX address.  You must use the -r
  175.             option in conjunction with these options.
  176.  
  177.             DLink will resolve all Absolute-Word addresses
  178.             but not all Absolute-Long addresses.  This is left
  179.             up to the ROMABLE program which generates a raw
  180.             binary image of the program that can then be
  181.             transfered to an EPROM.
  182.  
  183.             DO NOT USE WHEN GENERATING AMIGA EXECUTABLES
  184.  
  185.     -d[#]        debug mode (spews lots of debugging junk out)
  186.  
  187.     -E file        specify stderr file, any errors are appended to the file
  188.             instead of to stdout.  Useful for batch compiles
  189.  
  190.     -chip        chip-only - forces all hunks into CHIP memory
  191.  
  192.     -L0         remove default library search path, including all
  193.             explicitly specified (-L dir) directories up to
  194.             this point.
  195.  
  196.     -L dir        add the specified directory to the library search
  197.             path.  If the object module or library can not be
  198.             found in the current directory, directories
  199.             specified with -L are searched.  -L directories are
  200.             searched before the default library directory
  201.             (DLIB:), assuming it was not removed with -L0 .
  202.  
  203.             Note that the directory path specified by -L is used to
  204.             search for libraries AND object modules.
  205.  
  206.             A trailing '/' is optional
  207.  
  208.  
  209.             SPECIAL NOTE ON FRAGMENTATION
  210.  
  211.     When -frag is specified, the linker will not create a special
  212.     combined data+bss hunk (so data and bss can both be referenced with
  213.     one base variable).
  214.  
  215.     However, when -frag is NOT specified, the linker will stil not
  216.     necessarily combine ALL data hunks into one big hunk and ALL bss
  217.     hunks into one big hunk.  Any data or bss hunk with special upper
  218.     bits set (e.g. to force it into chip) is not combined into these
  219.     special hunks, and any data or bss hunk whos NAME begins with
  220.     'far' (upper or lower case) will also not be considered.
  221.  
  222.                 EXAMPLE
  223.  
  224.     This is what DCC gives the linker to link the program 'foo.c' :
  225.  
  226. dlink dlib:c.o @tmp dlib:x.o -o ram:foo
  227.  
  228. --- tmp ---
  229. foo.o
  230. dlib:c.lib dlib:amiga.lib dlib:auto.lib
  231. -----------
  232.  
  233.     Basically it tells dlink to link the startup code, c.o, then the
  234.     program object module(s) (foo.o), then c.lib, amiga.lib, and auto.lib,
  235.     then finally x.o.
  236.  
  237.     DCC handles all this for you
  238.  
  239.     auto.lib contains autoinit code for certain selected libraries,
  240.     including the dos.library.    Autoinit code is brought in whenever a
  241.     given library base symbol has been referenced BUT NOT DEFINED. auto.lib
  242.     defines the symbol and generates autoinit code to open the library and
  243.     autoexit code to close the library.  To maintain portability you
  244.     probably do not want to use this automatic library-openning feature
  245.     yourself, it is really meant to support certain actions of the DICE
  246.     library (such as floating point support).
  247.  
  248.     x.o terminates the autoinit and autoexit sections with an RTS. The
  249.     autoinit and autoexit sections are called from the startup code c.o .
  250.  
  251.